Requested by Jake Mor · Slack thread

This is Christo Todorov's feature; he greenlit the UX in the Slack thread above.

Before / After

Before — running npx superwall migrate detects your provider and then goes straight into a one-shot, end-to-end full migration: the agent edits your app source in place.

After — migrate first asks how you want to migrate:

• Plan first (the new default) — a read-only pass. The agent analyzes your provider integration and returns a step-by-step migration plan; the CLI writes it to sw-migration.md at your project root and copies implement the plan at sw-migration.md to your clipboard, so you can review the plan and then run it through your own agent when you're ready. No source files are touched.
• Migrate now — the existing behavior, unchanged: the agent performs the whole migration end to end.

The existing "how far?" scope select (Full migration / Paywalls only) is unchanged and still runs in both modes.

How

• src/commands/migrate.ts — a new mode select ("Plan first" / "Migrate now") runs right after the provider is detected, gated on ctx.interactive && !dryRun, defaulting the highlight to Plan first. The "how far?" select is kept as-is after it. The plan branch runs the new action, writes the returned report to <app>/sw-migration.md (root, not .superwall/), copies the run-prompt to the clipboard, and shows its own next-steps/outro.
• New migrate-plan action (src/core/agent/actions.ts) with READ capabilities, so Plan first is provably non-destructive — the agent cannot edit app source. It reuses the same superwall-migrate skill + provider reference and the same full/paywalls scope vars as migrate (shared migrateVars).
• New prompts/actions/migrate-plan.xml — instructs the agent to produce/return a complete, codebase-specific migration plan as its report and to modify no files; the CLI persists it. Mirrors migrate.xml, outputMode: "report".
• Clipboard reuse — copies implement the plan at sw-migration.md via copyToClipboard, mirroring copyIntegrationPrompt's UX in integrate/agent.ts (success note + manual-copy fallback).
• --plan flag (yargs) makes plan mode reachable non-interactively, threaded like --dry-run. Without it, non-interactive default stays migrate now.
• Sync sweep — printHelp() in src/cli.ts documents migrate [--plan], README.md's migrate section describes the new flow, and the print-skill switch handles the new action id.

Verification

• bun run build succeeds; bun run typecheck clean; bun run test green (81/81).

Follow-up

The bundled superwall-migrate skill is reused unchanged, so no skill content changed here. If the plan-first flow is later documented in the public superwall/skills repo's workflow router, a follow-up sync there may be needed — out of scope for this PR.

Generated by Claude Code